home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / FAQs / SGIfaqs / Dwarf-faq < prev    next >
Text File  |  1994-08-01  |  8KB  |  212 lines
  1.  
  2.                    ~4Dgifts/toolbox/FAQs/SGIfaqs Dwarf-faq
  3.  
  4.  
  5.            DWARF is a binary debugging-information format.
  6.     
  7.     The TFP compilers will produce debugging information in this format
  8.     rather than the format used in sherwood and earlier releases.
  9.     
  10.     Only people *writing* compilers, debuggers, or related tools
  11.     are affected directly by this change.
  12.     
  13.     These are the current DWARF topics:
  14.     
  15.         1) What is DWARF 
  16.         2) When will it appear
  17.         3) Documentation on DWARF
  18.         4) An Overview of DWARF Information Content
  19.         5) Can I Send This To My Friends?
  20.         6) Have a question about DWARF? *let us know*...
  21.     
  22.     Last revised: $Date: 1994/01/04 18:19:16 $
  23.     
  24.     1) What is DWARF 
  25.     
  26.     DWARF is a binary debugging-information-format.  It defines, in detail,
  27.     a way for compilers to tell debuggers about source programs.
  28.     
  29.     The 'final' specification of DWARF was approved by a committee of
  30.     (self-appointed) interested parties from a variety of companies in
  31.     March, 1993 by representatives from:  Sun Microsystems, IBM, Motorola
  32.     Inc, Intel, UNIX System Laboratories, Inc, Data General Corp, Digital
  33.     Equipment Corporation,  Ron Guilmette Computing, Eager Consulting, HAL
  34.     Computer Systems, Silicon Graphics
  35.     
  36.     The committee is operating  with support from UNIX International, the
  37.     body which will publish the DWARF specification.   However this support
  38.     does not restrict anyone: Anyone may use the specification in any way,
  39.     royalty-free.
  40.     
  41.     DWARF1 is the DWARF produced by USL's SVR4 compilers and used by their
  42.     debuggers.   It is no more capable than the MIPS mdebug symbol table
  43.     and is less dense than mdebug. We will not use DWARF1.
  44.     
  45.     SGI will be using DWARF 2.  It is capable of recording much more
  46.     detailed information than DWARF 1 and is far more compact (debugging
  47.     information in DWARF2 format takes much less space on disk than
  48.     debugging information in DWARF1 format).
  49.     
  50.     There are several reasons to change to this format (from MIPS mdebug,
  51.     which we use in all IRIX compiler releases so far, including sherwood).
  52.     
  53.     De-facto standard
  54.     
  55.       The intent and hope (of the committee members) is that the language
  56.       will become a de-facto-standard for debugging information.
  57.     
  58.       Note that a group of companies using Intel chips recently announced
  59.       joint 'support' for this. Meaning that the PC companies will have
  60.       at least some support in their debuggers and compilers.
  61.     
  62.       The GNU compilers (gcc, g++) now emit dwarf information on
  63.       many platforms.
  64.     
  65.     Handles many languages
  66.     
  67.       The initial report defines facilities to handle C, C++, Fortran(77
  68.       and 90) Pascal, and Modula 2.
  69.     
  70.     Extensible
  71.     
  72.       The report provides for extending DWARF. It guarantees to those doing
  73.       the extensions that future DWARF reports will not use certain
  74.       ranges of binary codes, thus guaranteeing that an extension
  75.       developed today will not be confused with future standard DWARF
  76.       features.
  77.     
  78.     Flexible
  79.     
  80.       DWARF2 already provides  means to describe such things as
  81.       arbitrary C #includes, C macros, C++ classes, C++ templates,
  82.       C++ exceptions, and Fortran COMMON (among other things).
  83.     
  84.       The result is that a debugger can, if it chooses, report accurately
  85.       to the debugger-user.
  86.     
  87.       Extension facilities in DWARF  make it possible to add sgi-specific
  88.       information into DWARF in future releases without breaking any
  89.       already-released DWARF-reading debuggers.
  90.     
  91.     2) When will it appear
  92.     
  93.       Work began in March, 1993.  Proposals on the functional interface
  94.       that compiler-writers and debugger-writers should use are listed in
  95.       the documentation section (faq dwarf 3).
  96.     
  97.       Working versions of DWARF libraries for producing and
  98.       consuming DWARF information are part of the ragnarok
  99.       compilers (compilers v4.00)
  100.     
  101.     3) Documentation on DWARF
  102.     
  103.       THE FOLLOWING FILES ARE IN toolbox/documents/Dwarf
  104.     
  105.       DWARF version 2 industry draft:  dwarf.v2.0.ps
  106.       An index                      :  dwarf.v2.0.indx.ps
  107.     
  108.     
  109.       A document proposing libdwarf consumer Application Programmer 
  110.       Interface (API) for DWARF VERSION 2.
  111.       Anyone writing a program which wants to read symbolic debugging
  112.       information from an object file would want to read this document.
  113.       Debugger writers (and those considering writing a debugger) will 
  114.       want to read this document.
  115.       About 60 pages --> libdwarf2.1.ps
  116.       
  117.     
  118.       An postscript document proposing libdwarf producer Application 
  119.       Programmer Interface (API) for DWARF VERSION 2.
  120.       Compiler writers will want to read this document.  
  121.       About 20 pages -->  libdwarf2p.1.ps
  122.     
  123.       Header files for dwarf and libdwarf. 
  124.            lp /hosts/quasar.mti/d/public/d/public/dwarf.h
  125.            lp /hosts/quasar.mti/d/public/d/public/libdwarf.h
  126.     
  127.     
  128.     
  129.     4) An Overview of Dwarf Information Content
  130.     
  131.     The documents mentioned in section 3 are long on details and short
  132.     on overview.  Lets try to put this all in to a total picture.
  133.     
  134.     To represent Debugging Information in an a.out we need several quite
  135.     different categories of information spread across various
  136.     ELF object file sections.
  137.     
  138.       A.  Information about code and data variables.
  139.           DWARF information is a tree of Debugging Information Entries (DIEs).
  140.           Each tree entry (Die) has a TAG which identifies what type
  141.           of entry it is and Attributes which give the details.
  142.           DIEs at the global level in a compilation unit are tied together
  143.           with Sibling Pointers.
  144.           Siblings are equal-level DIEs.
  145.           Children, on the other hand, are *owned* DIEs.
  146.           Lets adopt the following symbols for DIE relationships:
  147.         Sibling pointer  ->
  148.     
  149.         Child pointer    |
  150.                          v
  151.     
  152.           Here is a representation of the DIEs for t.c where types are 
  153.           left out to keep things simple (they don't change this, they
  154.           are just more DIEs to clutter things up):
  155.           t.c:
  156.         int foo(int i, int j) {  return 3;}
  157.         int goo;
  158.         
  159.     
  160.         Compilation_Unit 
  161.             |
  162.             v
  163.             function "foo"   -> global variable "goo " 
  164.                 |
  165.             v
  166.             parameter "i"    -> parameter "j"
  167.     
  168.         This goes in the .debug_info section with a tiny amount
  169.         of supporting data in .debug_abbrev
  170.       B.  Information about the mapping from code addresses to source
  171.           A separate section holds a very compact mapping from
  172.           code addresses to source lines (and columns).
  173.         This is in the .debug_line section.
  174.       C.  Information about C Macros
  175.           If desired, all C Macro #defines and #undef-s and 
  176.           #includes are recorded, with
  177.           the mapping back to the source files.
  178.         This is in the .debug_macinfo section.
  179.       D.  Information about unwinding stack frames
  180.           This is specially recorded in a section of its own: a seperate
  181.           small string of bytes per function/procedure.
  182.         This is in the .debug_frame section.
  183.     
  184.       Other .debug_* sections are for supporting data or for fast access to 
  185.       global names, types, and statics.
  186.     
  187.     6) Can I Send This To My Friends?
  188.     
  189.       dwarf.v2.0.ps and dwarf.v2.0.indx.ps
  190.       Yes.  These are the UI PLSIG committee industry review drafts.
  191.        
  192.     
  193.       The other documents are sgi-specific at this time.
  194.       The producer and consumer documents require more work, BTW.
  195.       
  196.       Personally, I think these should be distributable.
  197.       No one has hinted otherwise so far.
  198.       I hope to post them to the UI PLSIG committe as proposed
  199.       standards in 1994.  Or, rather, as starting points for
  200.       producer and consumer interface standards. [davea]
  201.     
  202.     6) Have a question about DWARF? *let us know*...
  203.     
  204.       We don't have any frequent questions yet :-)
  205.     
  206.       Send your question(s) on DWARF to
  207.     
  208.       davea@sgi.com
  209.     
  210.       The ragnarok compilers for TFP use dwarf as their debugging-information
  211.       format.
  212.